docs(skills): tag the 16 comment-carrying JSON fences jsonc - #7473

Fixes #7462

Sixteen fenced blocks under skills/objectui/ were tagged ```json while
their bodies carry // comments — syntax JSON forbids and JSONC allows. This
retags exactly those sixteen to ```jsonc. Tag-only: the whole diff is
sixteen opener lines.

What was counted, at the branch point 0246d11

skills/objectui/**/*.md holds 56 fences tagged json (and zero tagged jsonc).
17 of them fail JSON.parse — the card's figure, reproduced exactly:
12 in guides/schema-expressions.md, 4 in rules/protocol.md, 1 in rules/styling.md.

⚠️ The card's criterion and the card's number do not select the same set, and the
gap is exactly one block. Counting by "carries a // comment or a ... elision"
(the claim comment's wording) gives 16; counting by "fails JSON.parse" gives
17. The seventeenth is guides/schema-expressions.md:206, which uses no JSONC
feature at all — it is two top-level JSON documents listed in one fence. It keeps
its json tag, because jsonc would be a different false claim rather than a
truer one: the block's defect is that it is a listing, not that it is a dialect.
That is a judgement call, recorded here and on the card, and it is reversible in
one byte if the maintainer reads the card's headline number as the scope.

Sites retagged, per file

Each opener was asserted to be exactly the six bytes of the json info string
before it was rewritten; the retag script refuses the file otherwise.

Arithmetic

+1 byte per retagged fence, sixteen fences, sixteen bytes, zero line-count change.
git diff -U0 filtered to changed lines yields exactly 16 removals of the json
opener and 16 additions of the jsonc opener, and nothing else.

Token ratchet: none exists. No script in this repository budgets tokens, bytes
or lines over skills/**. The two budget scripts, check-eager-closure-budget.mjs
and render-budget-comment.mjs, measure the shipped JavaScript closure, not
markdown. The five scripts that read skills/ at all are
check-skill-examples.mjs, check-skills-paths.mjs, check-shell-escape-residue.mjs,
check-governed-queue-guard.mjs and check-doc-snippet-types.mjs (the last only to
NAME the tree as unscanned). So the arithmetic above is reported because the card
asked for it, not because anything gates on it.

What the tag buys, measured with the repository's own parser

check-skill-examples.mjs already implements both dialects — JSON_FENCE_LANGUAGES
is the set json, jsonc, and parseJsonFence strips comments and trailing commas
for jsonc only. Its header records the corpus state this pull request changes:
"There are zero jsonc fences in the corpus today; the language is recognised so
that adding one is not a silent no-op."

Running that exact function over the corpus, before and after:

So seven blocks become genuinely checkable — eligible for the gate's opt-in marker —
and nine do not. That residue is honest and is not repaired here, because
repairing it needs content edits and this flight is tag-only:

• seven list several top-level JSON documents in one fence
  (schema-expressions.md 32, 170, 447, 463, 479, 492; protocol.md 177);
• two carry ... elisions, which no JSON dialect accepts
  (protocol.md 157, 166);
• plus schema-expressions.md:206, which stays json, same listing shape.

Eleven blocks in total still parse under no dialect. They are recorded on the card
as a follow-up, not smuggled in here.

Decision: check-doc-fence-languages.mjs does NOT gain a skills/ root

The card asked whether this gate should be widened the way check-skills-paths.mjs
was by #7358. No — and the answer is measured rather than argued. Both legs
below ran against a throwaway mutation that added a skills walk to
listDocuments, proven on disk before any verdict was read (marker count 1, blob
hash de67f1d to 194926b) and restored byte-identically afterwards (hash back to
de67f1d, git diff HEAD for that path empty).

Leg A — the gate itself reds, in the one mode it can never absorb. Widened, it
exits 1 on skills/objectui/guides/project-setup.md:115: a ```javascript
fence whose first line is export default, which its quoted triage classifier calls
code. Because javascript is not in UNHIGHLIGHTED_SPELLINGS, that is UNKNOWN mode,
and the gate's header is explicit that UNKNOWN "⛔ can never be baselined and fails
on sight". So this is worse than the "would the baseline grow" test the card set:
the baseline could not take it at any size. Zero SYNONYM findings, one UNKNOWN.

Leg B — the widening is refused by the tree's own pin. The gate's scan surface is
pinned equal, element by element, to check-doc-snippet-types's by
scripts/__tests__/check-doc-fence-languages.test.ts ("walks exactly the documents
the snippet gate walks"). Under the mutation the two lists are 243 and 227 documents
and the assertion is false, the difference being exactly the 16 skills/objectui
pages. Widening this gate alone is therefore not a small edit; it is a three-gate
surface move.

And the surface owner has already been named. check-doc-snippet-types.mjs
states, beside UNGATED_DOCS: "⛔ skills/objectui/** is NOT claimed by any gate
here, and this line is the opposite of a claim on it: it is a governed, published
surface with its own review path, so pointing a doc gate at it is a decision for
whoever owns that surface — never a side effect of a root move." Doing it inside a
tag flight would be exactly the side effect that sentence forbids. For scale: that
gate is covered-by-default and compiles every ts/tsx fence it walks, and
skills/ holds 112 of them.

The four axes

• Real business need. Measured, not assumed: the population the widening would
  find in skills/ is ONE block, and it is a genuine JavaScript config example, not
  hidden TypeScript. There is no accumulation to catch here today. The need the card
  actually names — a tag that lies to a reader — is served in full by the retag,
  which the gate would not have caught either: it judges TypeScript bodies under
  non-TypeScript fences and says nothing whatsoever about json versus jsonc.
• Long-term soundness (the axis carrying at least half the weight). The durable
  shape is one surface decision made once, by the surface's owner, moving all three
  doc gates together with the UNGATED_DOCS accounting that decision implies. The
  patch-shaped alternative — widen one gate, then either re-fence a JavaScript block
  as TypeScript or add javascript to a set of spellings for unhighlighted blocks —
  buys one gate's reach by corrupting two vocabularies that other gates read. Both
  remedies are worse than the debt, and the debt is already written down by name.
• Preventing AI-authored mistakes. This is what decides the retag half and does
  not decide the widening half. An agent reading skills/objectui/ copies what the
  fence claims: a block tagged json carrying // teaches that comments are legal
  in the .json files it is about to write, and metadata files are exactly where
  that error would land silently. The fence gate would not have caught that in any
  configuration. Making the tag honest is the enforceable half available today;
  widening a TypeScript-body gate is not related to it.
• Startup scope discipline. A p3 truth item stays a p3 truth item. Turning it
  into a three-gate surface move plus a compile-coverage decision over a published,
  governed tree is the scope creep the focus principle exists to refuse. The debt
  stays named and unclaimed, which is the state that header calls strictly better
  than an unnamed one.

Consequently there is no self-test leg to add (the card's conditional step): no
gate changed, so no gate needs a new fixture. The reverse verification that WOULD
have accompanied a widening was still run, as the two ablation legs above — they are
what makes "do not widen" a measurement instead of a preference.

The tag is load-bearing, not cosmetic — proven both directions

A tag-only change invites the question "does anything actually read this?", so it
was answered against the live gate rather than asserted. Throwaway mutation on
rules/styling.md, under a trap, both legs proven on disk before any verdict was
read:

1. Opt the retagged fence in, tag left jsonc. Marker lines 3 to 4, blob
   06654f3 to 60b888c. check-skill-examples exits 0:
   "JSON phase: 40 fence(s) parsed, 0 failed."
2. Same block, same marker, tag flipped back to json. jsonc openers 1 to 0,
   blob 60b888c to 057fa51. The gate exits 1 and names the site:
   "[json] skills/objectui/rules/styling.md:171 Expected double-quoted property
   name in JSON at position 50 (line 3 column 31)."
3. Restore proven, not assumed: git checkout HEAD on the path, blob back to
   06654f3 — byte-identical to the HEAD blob — git diff HEAD for that path empty,
   marker count back to 3, jsonc openers back to 1.

So the retag moves seven blocks from "cannot be opted in without the gate going red"
to "can". Opting them in is a content edit and is NOT done here; it is the natural
follow-up and is recorded on the card.

An earlier attempt at this probe used a perl substitution whose anchor matched
nothing. It exited 0 with the file untouched — the classic green no-op — and was
caught only because the mutation is proven by hash and grep count before any verdict
is read. Recording it because the guard is the reason the numbers above mean
anything.

Gates

Every exit code was captured by redirect before any pipe, and each row quotes the
gate's own verdict line.

All ten runnable rows were re-run at the final commit ec67429 with a clean working
tree, and every exit code was captured by redirect before any pipe.

Not measured, and why

• Remote CI. Reported at draft time by dispatch contract; the merge-queue leg of
  Governed Surface Queue Guard cannot run on a draft at all.
• eslint over changed .mjs files. Nothing to run: the diff contains three
  markdown files and no script.
• Changeset. Not owed, by the presence gate's own verdict, quoted in the table.
• The nine jsonc fences and one json fence that still parse under no dialect.
  Their content is untouched by design; they are a follow-up on the card.
• Whether a widened trio of doc gates would pass over skills/. Deliberately not
  measured. Compiling 112 fences against built dist to cost a surface move nobody
  has authorised is the scope this pull request declines.

🤖 Generated with Claude Code

https://claude.ai/code/session_01LraLgQVGq8egUwfYZpbYt1

Generated by Claude Code

Queue fix (2026-09-04)

New head dc4811c. One commit on top of ec67429; nothing above this section
is changed, and no retag is reverted.

Why the queue rejected this pull request twice

packages/components/src/__tests__/skill-guide-data-table-binding.test.tsx reads the
real guides at run time, and its extractor was literal about the fence tag:

const fence = /```json\n([\s\S]*?)```/g;

rules/protocol.md's "bind": "customerNames" list example is one of the four
fences this branch retags, so a jsonc opener made it invisible to every assertion
in that file. Two of them read the absence as data:

• the counter-probe "still teaches bind in a JSON block" — "expected false to be true";
• "its list example renders one entry per bound item" — "the guide must carry a
  parseable list example bound with bind: expected undefined to be truthy".

The pull-request-level run never saw it: the "Decide whether this change needs a full
run" step trims the suite for a docs-only diff, and the full run is the merge_group
one. Same failure both ejections.

The fix

Widen the extractor to read both tags — the opener becomes jsonc? in the
same expression — and say so in the helper's doc comment. parseBlock already strips // comments before
JSON.parse, so jsonc bodies parse today; only the extractor was behind. The bind
block keeps its jsonc tag: those fences carry comments, which is the falsehood this
branch exists to remove.

Files: packages/components/src/__tests__/skill-guide-data-table-binding.test.tsx and
.changeset/jsonc-fence-extractor-test-only.md (empty frontmatter — a test-only change
declared as releasing nothing; the presence gate demanded a declaration once a
packages/components/src file entered the diff, and this is its explicit pass form).

Counts, re-derived at this head

A faithful re-implementation of jsonBlocks + parseBlock, run over the three guides
the test names, narrow tag then widened — fences / data-table / list /
bind=customerNames / offenders:

The data-table count is unchanged at 1 / 0 / 1, so expect(extra).toEqual([]) and
the [taught] node selection are untouched; the offenders list stays empty; the two
failing assertions get their block back. The newly visible protocol.md node is the
shape the other two guides already carry, character for character:
{"type":"list","bind":"customerNames"} — which is why widening it renders rather
than merely parses. guides/data-integration.md is untouched by this branch and stays
untouched; the widening only makes a future retag there safe.

Reverse verification — one mutation, proven on disk before any verdict was read

Restore the narrow json-only extractor on the committed state, under an
EXIT/INT/TERM trap with an absolute path:

1. Mutation proven, not assumed. File back to blob 421bca4 — byte-identical to
   the parent's blob for that path — widened-regex count 0, narrow-regex count
   1, all three read before the test ran.
2. Exactly the two named assertions red, and nothing else. "Tests 2 failed | 14
   passed (16)", "Test Files 1 failed (1)", with the two messages quoted above. Lock
   verdict: "command-exit 1".
3. Restore proven. Hash back to 76fdb28, git diff HEAD for that path empty,
   working tree clean at the final commit.

With the fix, the same whole-file command: "Test Files 1 passed (1)" / "Tests 16
passed (16)", lock verdict "command-exit 0".

Gates, re-run at dc4811c with a clean working tree

Every exit code captured by redirect before any pipe; each row quotes the gate's own
verdict line.

Not measured, and why

• Remote CI, including the merge_group run. Reported at push time by dispatch
  contract. The whole-file run above is the local stand-in for the queue's full run.
• tsc -p tsconfig.scripts.json. Does not apply: the changed file belongs to
  @object-ui/components, whose own type-check chains tsconfig.test.json, and that
  is the project that reads it.
• The repository-wide pnpm lint. Narrowed to the one changed PACKAGE, and the
  narrowing is measured rather than asserted. Population read from eslint's own config:
  the root flat config extends tseslint.configs.recommended, not the type-checked
  variant, and its languageOptions names no parserOptions.project or
  projectService — so no file's verdict depends on a TypeScript program, and a diff
  inside packages/components cannot move the verdict of a file in another package.
  File count read from --format json: eslint . in packages/components judged
  448 files, 0 errors (934 pre-existing warnings), exit 0, and the edited file is in
  that judged set.
• The nine jsonc fences and one json fence that still parse under no dialect.
  Unchanged by this section, still the follow-up recorded on the card.

What this needs from a human

The earlier approving review was pinned to ec67429. The new head dc4811c needs a
fresh approval pinned to it before the merge queue will take this pull request —
that is the approver's action. Nothing here touched the draft/ready state, reviewers,
labels, auto-merge, or queue membership; the push landed only because the failing
group had already dequeued this pull request on its own.